---
title: "Reference: Memory API | Client SDK"
description: Learn how to manage conversation threads and message history in Mastra using the client-js SDK.
---

# Memory API

The Memory API provides methods to manage conversation threads and message history in Mastra.

### Get All Threads

Retrieve all memory threads for a specific resource:

```typescript
const threads = await mastraClient.getMemoryThreads({
  resourceId: "resource-1",
  agentId: "agent-1",
});
```

### Create a New Thread

Create a new memory thread:

```typescript
const thread = await mastraClient.createMemoryThread({
  title: "New Conversation",
  metadata: { category: "support" },
  resourceId: "resource-1",
  agentId: "agent-1",
});
```

### Working with a Specific Thread

Get an instance of a specific memory thread:

```typescript
const thread = mastraClient.getMemoryThread({ threadId: "thread-id", agentId: "agent-id" });
```

## Thread Methods

### Get Thread Details

Retrieve details about a specific thread:

```typescript
const details = await thread.get();
```

### Update Thread

Update thread properties:

```typescript
const updated = await thread.update({
  title: "Updated Title",
  metadata: { status: "resolved" },
  resourceId: "resource-1",
});
```

### Delete Thread

Delete a thread and its messages:

```typescript
await thread.delete();
```

## Message Operations

### Save Messages

Save messages to memory:

```typescript
const savedMessages = await mastraClient.saveMessageToMemory({
  messages: [
    {
      role: "user",
      content: "Hello!",
      id: "1",
      threadId: "thread-1",
      resourceId: "resource-1",
      createdAt: new Date(),
      format: 2,
    },
  ],
  agentId: "agent-1",
});
```

### Retrieve Thread Messages

Get messages associated with a memory thread:

```typescript
// Get all messages in the thread (paginated)
const result = await thread.listMessages();
console.log(result.messages); // Array of messages
console.log(result.total); // Total count
console.log(result.hasMore); // Whether more pages exist

// Get messages with pagination
const result = await thread.listMessages({
  page: 0,
  perPage: 20
});

// Get messages with ordering
const result = await thread.listMessages({
  orderBy: { field: 'createdAt', direction: 'ASC' }
});
```

### Delete Messages

Delete one or more messages from a thread:

```typescript
// Delete a single message
const result = await thread.deleteMessages("message-id");

// Delete multiple messages
const result = await thread.deleteMessages([
  "message-1",
  "message-2",
  "message-3",
]);

// Returns: { success: true, message: "Message deleted successfully" }
```

## Working Memory

Working memory allows agents to maintain persistent information about users across interactions. It can be scoped to either a specific thread or across all threads for a resource (user).

### Get Working Memory

Retrieve the current working memory for a thread:

```typescript
const workingMemory = await mastraClient.getWorkingMemory({
  agentId: "agent-1",
  threadId: "thread-1",
  resourceId: "user-123", // Optional, required for resource-scoped memory
});
```

The response includes:
- `workingMemory`: The current working memory content (string or null)
- `source`: Whether the memory is from `"thread"` or `"resource"` scope
- `workingMemoryTemplate`: The template used for working memory (if configured)
- `threadExists`: Whether the thread exists

### Update Working Memory

Update the working memory content for a thread:

```typescript
await mastraClient.updateWorkingMemory({
  agentId: "agent-1",
  threadId: "thread-1",
  workingMemory: `# User Profile
- Name: John Doe
- Location: New York
- Preferences: Prefers formal communication
`,
  resourceId: "user-123", // Optional, required for resource-scoped memory
});

// Returns: { success: true }
```

**Note:** For resource-scoped working memory, you must provide the `resourceId` parameter. This allows the memory to persist across all conversation threads for that user.

### Get Memory Status

Check the status of the memory system:

```typescript
const status = await mastraClient.getMemoryStatus("agent-id");
```
